Aminet 8/Aminet 8 (1995)(GTI - Schatztruhe)[!][Oct 1995].iso/Aminet/comm/bbs/MAX_DoorPack.lha/MAX_DoorPack103/DoorPack.doc

Text File | 1995-08-19 | 9KB | 248 lines

    Summary for file Descriptions:

        A C starter pack for people wishing to write doors.
        Bugfixed release...

                             _______________
                            |               |
                            |   DOORPACK    |
                            |               |
                            |    v 1.03     |
                            |_______________|

                              for MAX's BBS

                  Written by Paul Mclachlan of Dataline
                Call Serious Operations BBS [phone]


            DoorPack bug-fixed and expanded by Marcin Orlowski
                Call Silver Dream!'s BBS  [phone]


    INTRODUCTION:

        DoorPack is similar to DoorStarter written by Anthony Barrett,
        except that DoorPack is documented much better, and the source is
        written in C.  This was done for two reasons:

                a)  There was no correct C code for Doors in MAX's.
                Programmers had to re-invent the wheel for every door.

                b)  Only one other person knew nearly enough about writing
                doors for MAX's, and they program in BASIC!  So, I
                gathered everything together and produced the definitive
                MAX Doors pack.

    NEW IN VERSION 1.01:

        In version 1.01, code supplied by Robert Masters has been placed
        at the end of the DoorPack.h header file which deals with the MAX
        config files.  They are a group of structures that will make
        reading and utilising these structures much easier.  Thanks
        Robert!

    NEW IN VERSION 1.03:

      AS BUGFIX:

        Well... this doorpack is very useful thing for all
        the people who wants to write its own door for MAX's
        BBS, and thanks to DataLine for creating it.
        Unfortunately, as almost every software worldwide,
        the little, but very annoying bug was also included
        to this pack, which caused bad reference to MAX's
        config file. The thing is that SERIAL_DEV_UNIT is
        stored by MAX's as WORD not as ULONG! And that the
        point is. And all goes right until you want to read
        any data lying after SERIAL_DEV_UNIT field. I guess
        you want to, because all sections description are
        stored exactly there...

      AS EXPANSION:

        Some #defines have been made to easy use getsvar() and getsnum()
        (see the end of the doorpack.h).


                                                Marcin Orlowski
                                          ([e-mail])


    USAGE:

        To actually use the doorpack is simplicity itself (providing you
        can program in C).  Simply LINK the DoorPack.o with your code, and
        your code should start with dmain() instead of main().  Main() is
        actually defined in DoorPack.o, which automatically sets up the
        door ports and everything.  Then, simply call the routines as
        required.  As an example, to write a door which writes: "Hello BBS
        World!" when run (a stupid silly, but small example):

                #include "DoorPack.h"
                void dmain( void )
                    {
                    sendmessage( "Hello BBS World!", 1 );
                    }

        See!  Its that easy.  A guide to the individual routines follows.

    REFERENCE:

        As you can see from the header file, there are more than a few
        functions defined.  The actual descriptions of these are listed
        here:

        void end( void );

            This routine prematurely ends the Door.  If called your door
            will exit totally.  Not really needed.  Just return from
            dmain, as it is automatically called after dmain.  btw - NEVER
            exit(); from dmain.  This is exceptionally bad.

        void getsvar( int typ, char *mstring );

            This routine gets some string variables about the user or
            MAX's, depending upon typ:

                1: Users name
                2: Users password
                3: Suburb
                4: Users City? (paragon function)
                5: Users state (paragon function)
                6: Users post/zip code (paragon function)
                7: Path to the doors
                8: main BBS path
                9: Date
                10: Time
                100: Phone number
                101: Computer type
                102: Comment (as defined by Sysop)

            The returned string is written in your buffer mstring.

        void sendmessage( char mstring[], int nl );

            This routine outputs the string mstring from the door.  The nl
            is set to 1 if you want a cr/lf sequence sent after the
            string, or 0 if you do not want this.

        void hotkey( char mstring[], char *ostring );

            This routine outputs the string mstring, and waits for a key
            to be hit.  This key that was hit is stored in ostring[0].

        void prompt( char mstring[], char *ostring, int len );

            This routine displays mstring, and allows the user to enter a
            string.  This is returned in ostring.  MAX will not allow the
            string returned to exceed len characters.

        void sprompt( char mstring[], char *ostring, int len );

            This is the same as prompt, except it will also handle stacked
            commands correctly.  (If you use a / in your command, then
            everything after the / is for the next line that comes up -
            under paragon anyway.)

    void showfile( char mstring[] );

            This TYPE's a file from the door.  It will output the file to
            the BBS - just like the type command, except to the board.

    void twituser( void );

            This will cause MAX's to hang up.

    void addtime( int howmuch );

            This will add howmuch time to the users current remaining
            time.  This howmuch can also be negative, subtracting time.

    void newaccess( int now );

            This sets the users access to now.

    void MenuFunction( int function, int extra, char *string );

            This command executes the MAX's BBS menu function specified.
            This is exactly the same as in the configuration of the menus.
            The function (1-33) is the menu function ie, 3 will page the
            sysop etc. (See Menufunctions.text on the MAX's disk), while
            extra is the extra of that function, and string is the string
            of that function.

    void localmessage( char mstring[], int nl );

            This will output a string that is only visible on the local
            MAX's screen. ie, it is not sent through the modem.  nl is the
            same as for sendmessage.

    void putmodemchar( char outd );

            This will output a character to the modem only (not visible to
            the screen).

    void putscreenchar( char outd );

            This will output a character to the screen (local) only.

    void putdoorchar( char outd );

            This will output a character to the screen and modem,
            as normal.

    void editfile( char mstring[], int maxlines );

            This will edit the filename contained in mstring, which it
            will not allow to exceed maxlines in length.

    int chkfile( char *filename );

            This will check to see if filename is available to MAX's.
            Returns 1 if it is available, or -1 if it is locked or not
            found.  This command accepts wildcards, and if so, will return
            in filename the actual name of the file that it found.

    int getsnum( int typ );

            This is sort of the same as getsvar, except that it gets
            integer information about the user.  a Typ of:

                1:  Access Level
                2:  Expert mode?  (Paragon)
                3:  Net Credits?  (paragon)
                4:  Number of calls
                5:  Calls to system
                6:  Graphics mode
                7:  Minutes remaining
                8:  Screen columns
                9:  Screen rows


    ALSO IN THE ARCHIVE:

        Also included in this archive is the various offsets in the MAX's
        config files, ie:  file.data, file.index, bbs.config, etc.  These
        were kindly supplied by Randy Quick.  These files are necessary if
        you need to do anything really serious with some different aspects
        of the doors.  They allow you to find out everything that MAX's
        keeps on disk about the configuration of the BBS.


    FINALLY:

        Dataline is a group of coders and artists committed to producing
        software for the Amiga.  Consisting of:

                    Paul Mclachlan  (coding)
                    Lee Adamson (coding)
                    Chris Burton (coding)
                    Lada Trejbal (music)

        You can contact us on the Dataline support board [phone].  I
        (Paul Mclachlan) am sysop on the board.  Alternatively you can
        contact us through MAX's NET.